home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Connection.java < prev    next >
Text File  |  1998-09-22  |  12KB  |  307 lines
  1. /*
  2.  * @(#)Connection.java    1.6 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.sql;
  16.  
  17. /**
  18.  * <P>A Connection represents a session with a specific
  19.  * database. Within the context of a Connection, SQL statements are
  20.  * executed and results are returned.
  21.  *
  22.  * <P>A Connection's database is able to provide information
  23.  * describing its tables, its supported SQL grammar, its stored
  24.  * procedures, the capabilities of this connection, etc. This
  25.  * information is obtained with the getMetaData method.
  26.  *
  27.  * <P><B>Note:</B> By default the Connection automatically commits
  28.  * changes after executing each statement. If auto commit has been
  29.  * disabled, an explicit commit must be done or database changes will
  30.  * not be saved.
  31.  *
  32.  * @see DriverManager#getConnection
  33.  * @see Statement 
  34.  * @see ResultSet
  35.  * @see DatabaseMetaData
  36.  */
  37. public interface Connection {
  38.  
  39.     /**
  40.      * SQL statements without parameters are normally
  41.      * executed using Statement objects. If the same SQL statement 
  42.      * is executed many times, it is more efficient to use a 
  43.      * PreparedStatement
  44.      *
  45.      * @return a new Statement object 
  46.      * @exception SQLException if a database-access error occurs.
  47.      */
  48.     Statement createStatement() throws SQLException;
  49.  
  50.     /**
  51.      * A SQL statement with or without IN parameters can be
  52.      * pre-compiled and stored in a PreparedStatement object. This
  53.      * object can then be used to efficiently execute this statement
  54.      * multiple times.
  55.      *
  56.      * <P><B>Note:</B> This method is optimized for handling
  57.      * parametric SQL statements that benefit from precompilation. If
  58.      * the driver supports precompilation, prepareStatement will send
  59.      * the statement to the database for precompilation. Some drivers
  60.      * may not support precompilation. In this case, the statement may
  61.      * not be sent to the database until the PreparedStatement is
  62.      * executed.  This has no direct affect on users; however, it does
  63.      * affect which method throws certain SQLExceptions.
  64.      *
  65.      * @param sql a SQL statement that may contain one or more '?' IN
  66.      * parameter placeholders
  67.      * @return a new PreparedStatement object containing the
  68.      * pre-compiled statement 
  69.      * @exception SQLException if a database-access error occurs.
  70.      */
  71.     PreparedStatement prepareStatement(String sql)
  72.         throws SQLException;
  73.  
  74.     /**
  75.      * A SQL stored procedure call statement is handled by creating a
  76.      * CallableStatement for it. The CallableStatement provides
  77.      * methods for setting up its IN and OUT parameters, and
  78.      * methods for executing it.
  79.      *
  80.      * <P><B>Note:</B> This method is optimized for handling stored
  81.      * procedure call statements. Some drivers may send the call
  82.      * statement to the database when the prepareCall is done; others
  83.      * may wait until the CallableStatement is executed. This has no
  84.      * direct affect on users; however, it does affect which method
  85.      * throws certain SQLExceptions.
  86.      *
  87.      * @param sql a SQL statement that may contain one or more '?'
  88.      * parameter placeholders. Typically this  statement is a JDBC
  89.      * function call escape string.
  90.      * @return a new CallableStatement object containing the
  91.      * pre-compiled SQL statement 
  92.      * @exception SQLException if a database-access error occurs.
  93.      */
  94.     CallableStatement prepareCall(String sql) throws SQLException;
  95.                         
  96.     /**
  97.      * A driver may convert the JDBC sql grammar into its system's
  98.      * native SQL grammar prior to sending it; nativeSQL returns the
  99.      * native form of the statement that the driver would have sent.
  100.      *
  101.      * @param sql a SQL statement that may contain one or more '?'
  102.      * parameter placeholders
  103.      * @return the native form of this statement
  104.      * @exception SQLException if a database-access error occurs.
  105.      */
  106.     String nativeSQL(String sql) throws SQLException;
  107.  
  108.     /**
  109.      * If a connection is in auto-commit mode, then all its SQL
  110.      * statements will be executed and committed as individual
  111.      * transactions.  Otherwise, its SQL statements are grouped into
  112.      * transactions that are terminated by either commit() or
  113.      * rollback().  By default, new connections are in auto-commit
  114.      * mode.
  115.      *
  116.      * The commit occurs when the statement completes or the next
  117.      * execute occurs, whichever comes first. In the case of
  118.      * statements returning a ResultSet, the statement completes when
  119.      * the last row of the ResultSet has been retrieved or the
  120.      * ResultSet has been closed. In advanced cases, a single
  121.      * statement may return multiple results as well as output
  122.      * parameter values. Here the commit occurs when all results and
  123.      * output param values have been retrieved.
  124.      *
  125.      * @param autoCommit true enables auto-commit; false disables
  126.      * auto-commit.  
  127.      * @exception SQLException if a database-access error occurs.
  128.      */
  129.     void setAutoCommit(boolean autoCommit) throws SQLException;
  130.  
  131.     /**
  132.      * Get the current auto-commit state.
  133.      *
  134.      * @return Current state of auto-commit mode.
  135.      * @exception SQLException if a database-access error occurs.
  136.      * @see #setAutoCommit 
  137.      */
  138.     boolean getAutoCommit() throws SQLException;
  139.  
  140.     /**
  141.      * Commit makes all changes made since the previous
  142.      * commit/rollback permanent and releases any database locks
  143.      * currently held by the Connection. This method should only be
  144.      * used when auto commit has been disabled.
  145.      *
  146.      * @exception SQLException if a database-access error occurs.
  147.      * @see #setAutoCommit 
  148.      */
  149.     void commit() throws SQLException;
  150.  
  151.     /**
  152.      * Rollback drops all changes made since the previous
  153.      * commit/rollback and releases any database locks currently held
  154.      * by the Connection. This method should only be used when auto
  155.      * commit has been disabled.
  156.      *
  157.      * @exception SQLException if a database-access error occurs.
  158.      * @see #setAutoCommit 
  159.      */
  160.     void rollback() throws SQLException;
  161.  
  162.     /**
  163.      * In some cases, it is desirable to immediately release a
  164.      * Connection's database and JDBC resources instead of waiting for
  165.      * them to be automatically released; the close method provides this
  166.      * immediate release. 
  167.      *
  168.      * <P><B>Note:</B> A Connection is automatically closed when it is
  169.      * garbage collected. Certain fatal errors also result in a closed
  170.      * Connection.
  171.      *
  172.      * @exception SQLException if a database-access error occurs.
  173.      */
  174.     void close() throws SQLException;;
  175.  
  176.     /**
  177.      * Tests to see if a Connection is closed.
  178.      *
  179.      * @return true if the connection is closed; false if it's still open
  180.      * @exception SQLException if a database-access error occurs.
  181.      */
  182.     boolean isClosed() throws SQLException;;
  183.  
  184.     //======================================================================
  185.     // Advanced features:
  186.  
  187.     /**
  188.      * A Connection's database is able to provide information
  189.      * describing its tables, its supported SQL grammar, its stored
  190.      * procedures, the capabilities of this connection, etc. This
  191.      * information is made available through a DatabaseMetaData
  192.      * object.
  193.      *
  194.      * @return a DatabaseMetaData object for this Connection 
  195.      * @exception SQLException if a database-access error occurs.
  196.      */
  197.     DatabaseMetaData getMetaData() throws SQLException;;
  198.  
  199.     /**
  200.      * You can put a connection in read-only mode as a hint to enable 
  201.      * database optimizations.
  202.      *
  203.      * <P><B>Note:</B> setReadOnly cannot be called while in the
  204.      * middle of a transaction.
  205.      *
  206.      * @param readOnly true enables read-only mode; false disables
  207.      * read-only mode.  
  208.      * @exception SQLException if a database-access error occurs.
  209.      */
  210.     void setReadOnly(boolean readOnly) throws SQLException;
  211.  
  212.     /**
  213.      * Tests to see if the connection is in read-only mode.
  214.      *
  215.      * @return true if connection is read-only
  216.      * @exception SQLException if a database-access error occurs.
  217.      */
  218.     boolean isReadOnly() throws SQLException;
  219.  
  220.     /**
  221.      * A sub-space of this Connection's database may be selected by setting a
  222.      * catalog name. If the driver does not support catalogs it will
  223.      * silently ignore this request.
  224.      *
  225.      * @exception SQLException if a database-access error occurs.
  226.      */
  227.     void setCatalog(String catalog) throws SQLException;
  228.  
  229.     /**
  230.      * Return the Connection's current catalog name.
  231.      *
  232.      * @return the current catalog name or null
  233.      * @exception SQLException if a database-access error occurs.
  234.      */
  235.     String getCatalog() throws SQLException;
  236.  
  237.     /**
  238.      * Transactions are not supported. 
  239.      */
  240.     int TRANSACTION_NONE         = 0;
  241.  
  242.     /**
  243.      * Dirty reads, non-repeatable reads and phantom reads can occur.
  244.      */
  245.     int TRANSACTION_READ_UNCOMMITTED = 1;
  246.  
  247.     /**
  248.      * Dirty reads are prevented; non-repeatable reads and phantom
  249.      * reads can occur.
  250.      */
  251.     int TRANSACTION_READ_COMMITTED   = 2;
  252.  
  253.     /**
  254.      * Dirty reads and non-repeatable reads are prevented; phantom
  255.      * reads can occur.     
  256.      */
  257.     int TRANSACTION_REPEATABLE_READ  = 4;
  258.  
  259.     /**
  260.      * Dirty reads, non-repeatable reads and phantom reads are prevented.
  261.      */
  262.     int TRANSACTION_SERIALIZABLE     = 8;
  263.  
  264.     /**
  265.      * You can call this method to try to change the transaction
  266.      * isolation level using one of the TRANSACTION_* values.
  267.      *
  268.      * <P><B>Note:</B> setTransactionIsolation cannot be called while
  269.      * in the middle of a transaction.
  270.      *
  271.      * @param level one of the TRANSACTION_* isolation values with the
  272.      * exception of TRANSACTION_NONE; some databases may not support
  273.      * other values
  274.      * @exception SQLException if a database-access error occurs.
  275.      * @see DatabaseMetaData#supportsTransactionIsolationLevel 
  276.      */
  277.     void setTransactionIsolation(int level) throws SQLException;
  278.  
  279.     /**
  280.      * Get this Connection's current transaction isolation mode.
  281.      *
  282.      * @return the current TRANSACTION_* mode value
  283.      * @exception SQLException if a database-access error occurs.
  284.      */
  285.     int getTransactionIsolation() throws SQLException;
  286.  
  287.     /**
  288.      * The first warning reported by calls on this Connection is
  289.      * returned.  
  290.      *
  291.      * <P><B>Note:</B> Subsequent warnings will be chained to this
  292.      * SQLWarning.
  293.      *
  294.      * @return the first SQLWarning or null 
  295.      * @exception SQLException if a database-access error occurs.
  296.      */
  297.     SQLWarning getWarnings() throws SQLException;
  298.  
  299.     /**
  300.      * After this call, getWarnings returns null until a new warning is
  301.      * reported for this Connection.  
  302.      *
  303.      * @exception SQLException if a database-access error occurs.
  304.      */
  305.     void clearWarnings() throws SQLException;
  306. }
  307.